Providers

Providers connect BindAI agents to language models. BindAI separates agent configuration from the underlying model provider so applications can select different providers without changing the overall agent architecture. The provider layer defines a common interface for model generation and streaming, while provider-specific packages implement communication with individual model services.

Provider Architecture

The relationship between an application, agent, provider, and model can be represented as:

Application
    |
    v
  Agent
    |
    v
 Provider
    |
    v
Language Model

The provider is responsible for translating BindAI model requests into provider-specific operations and returning BindAI model responses. The core provider abstraction exposes:

Provider name
Model generation
Streaming
Provider capabilities
Provider configuration

The exact capabilities available during execution depend on the selected provider and model.

Supported Providers

The current BindAI provider configuration and bootstrap system recognizes:

OpenAI
Anthropic
Google
Groq
Ollama
OpenRouter

Provider integrations are loaded through the provider bootstrap process when their provider packages are available. The provider registry exposes a common registration and creation interface over the canonical provider registry in bindai-core.

Configuring a Model

The recommended way to select a model is through Agent.builder().

from bindai import Agent

agent = (
    Agent.builder()
    .name("assistant")
    .model("openai:gpt-4.1-mini")
    .instructions("You are a helpful assistant.")
    .build()
)

The model string uses the following format:

provider:model

For example:

openai:gpt-4.1-mini

The provider prefix identifies the provider, while the remaining value identifies the model.

Provider-Qualified Models

Provider-qualified model names allow the application to select a provider and model through a single configuration value. For example:

.model("openai:gpt-4.1-mini")

Another provider can be selected with:

.model("anthropic:claude-sonnet-4")

or:

.model("google:gemini-2.5-flash")

or:

.model("groq:llama-3.3-70b-versatile")

or a locally hosted Ollama model:

.model("ollama:llama3")

or an OpenRouter model:

.model("openrouter:openai/gpt-4.1-mini")

The exact model identifier must be supported by the selected provider.

Provider Configuration

Providers receive a common ProviderConfiguration object. The configuration contains:

ProviderConfiguration(
    api_key=None,
    endpoint=None,
    organization=None,
    model=None,
    timeout=60,
    headers={},
)

The fields provide common configuration that provider implementations can use:

api_key — provider authentication credential.
endpoint — provider or service endpoint.
organization — provider organization identifier when applicable.
model — selected model identifier.
timeout — request timeout in seconds; the default is 60.
headers — additional request headers.

Provider implementations may use only the configuration fields relevant to their service.

Environment Variables

Provider credentials should not be hardcoded into application source code. The BindAI provider configuration layer recognizes environment variables for the supported providers. For example:

OPENAI_API_KEY=your_api_key_here
ANTHROPIC_API_KEY=your_api_key_here
GEMINI_API_KEY=your_api_key_here
GROQ_API_KEY=your_api_key_here
OPENROUTER_API_KEY=your_api_key_here

Ollama uses an endpoint configuration rather than requiring a hosted-provider API key. The provider configuration layer also recognizes provider-specific endpoint and organization variables where applicable. Store sensitive configuration in environment variables, project-scoped connections, or an appropriate secret-management system. Never commit API keys or other credentials to source control.

Project-Scoped Provider Connections

BindAI can also select provider credentials through named project-scoped connections. For example:

provider = "openai"
connection = "work"
model = "gpt-4.1-mini"

The connection metadata identifies the provider while the credential is stored separately in the operating system credential store. Connections can be managed through the CLI:

bindai connections add
bindai connections list
bindai connections remove

Provider credential resolution follows this precedence:

Explicitly supplied API key.
Credential stored for the selected project connection.
Provider environment variable.

A configured connection must exist, must match the selected provider, and must have a stored credential when the provider requires one. See the Connections documentation for the complete project-scoped credential workflow.

Provider Interface

The canonical provider abstraction is ModelProvider. A provider implementation receives a ProviderConfiguration and implements:

class ModelProvider(ABC):
    def __init__(self, configuration):
        self.configuration = configuration

    @property
    @abstractmethod
    def name(self) -> str:
        ...

    @abstractmethod
    def generate(self, request):
        ...

    @abstractmethod
    def stream(self, request):
        ...

    @property
    @abstractmethod
    def capabilities(self):
        ...

The two primary model operations are:

generate() for normal model execution.
stream() for streaming model execution.

The capabilities property describes the features exposed by the provider implementation.

Provider Capabilities

BindAI represents provider capabilities through ProviderCapabilities. The capability model includes:

ProviderCapabilities(
    chat=True,
    streaming=False,
    vision=False,
    embeddings=False,
    tool_calling=False,
    structured_output=False,
    reasoning=False,
)

The available capability fields are:

chat
streaming
vision
embeddings
tool_calling
structured_output
reasoning

These flags describe capabilities exposed by a provider implementation. Applications should not assume that every provider or model supports every capability. For example, an application that depends on tool calling should verify that the selected provider/model combination supports tool calling before relying on it.

Provider Registry

BindAI exposes ProviderRegistry for provider registration and discovery. For example:

from bindai_providers import ProviderRegistry

print(ProviderRegistry.list())

The registry provides operations for:

Registering providers
Unregistering providers
Checking whether a provider exists
Retrieving a provider
Creating a provider
Listing registered providers
Clearing registrations

The provider registry in bindai-providers acts as a compatibility facade over the canonical ProviderFactory in bindai-core. This keeps provider creation consistent with the core provider architecture.

Provider Bootstrap

BindAI initializes supported provider integrations through provider bootstrap. The bootstrap process attempts to load the provider modules for the supported provider integrations:

Provider Bootstrap
    |
    +---- OpenAI
    |
    +---- Anthropic
    |
    +---- Google
    |
    +---- Groq
    |
    +---- Ollama
    |
    +---- OpenRouter

If a provider module is not installed, bootstrap skips that provider. This allows provider integrations to remain modular rather than requiring every provider implementation to be available in every environment.

OpenAI

OpenAI models can be selected using the openai provider prefix.

from bindai import Agent

agent = (
    Agent.builder()
    .name("assistant")
    .model("openai:gpt-4.1-mini")
    .instructions("You are a helpful assistant.")
    .build()
)

The selected model must be available through the configured OpenAI provider environment. OpenAI provider support is exposed through the common BindAI provider interface. Applications should verify the capabilities of the selected model before depending on features such as tool calling, structured output, vision, or streaming.

Anthropic

Anthropic models can be selected using the anthropic provider prefix.

from bindai import Agent

agent = (
    Agent.builder()
    .name("assistant")
    .model("anthropic:claude-sonnet-4")
    .instructions("You are a helpful assistant.")
    .build()
)

The selected model must be available through the configured Anthropic provider environment. Provider and model capabilities should be verified before relying on features such as tool calling, structured output, or streaming.

Google Gemini

Google Gemini models can be selected using the google provider prefix.

from bindai import Agent

agent = (
    Agent.builder()
    .name("assistant")
    .model("google:gemini-2.5-flash")
    .instructions("You are a helpful assistant.")
    .build()
)

The selected model must be available through the configured Google provider environment. The exact capabilities available to an application depend on the selected model and provider implementation.

Groq

Groq models can be selected using the groq provider prefix.

from bindai import Agent

agent = (
    Agent.builder()
    .name("assistant")
    .model("groq:llama-3.3-70b-versatile")
    .instructions("You are a helpful assistant.")
    .build()
)

The selected model identifier must be supported by the configured Groq service. The provider uses the same BindAI model-provider abstraction as the other hosted providers.

Ollama

Ollama models can be selected through the ollama provider prefix.

from bindai import Agent

agent = (
    Agent.builder()
    .name("assistant")
    .model("ollama:llama3")
    .instructions("You are a helpful assistant.")
    .build()
)

This allows an application to use a locally hosted model while keeping the agent configuration otherwise similar. The selected model must be available in the local Ollama environment. The provider configuration layer supports the Ollama endpoint environment variable:

OLLAMA_HOST=http://localhost:11434

Ollama can therefore be used without a hosted-provider API key.

OpenRouter

OpenRouter models can be selected through the openrouter provider prefix.

from bindai import Agent

agent = (
    Agent.builder()
    .name("assistant")
    .model("openrouter:openai/gpt-4.1-mini")
    .instructions("You are a helpful assistant.")
    .build()
)

The model identifier must be supported by the configured OpenRouter service. OpenRouter models participate in the same BindAI provider abstraction as other providers.

Provider and Agent Configuration

Provider configuration and agent behavior are separate concerns. For example:

agent = (
    Agent.builder()
    .name("researcher")
    .model("openai:gpt-4.1-mini")
    .instructions(
        """
        You are a research assistant.
        Provide concise, factual answers.
        """
    )
    .build()
)

Here:

model() selects the provider and model.
instructions() defines agent behavior.
build() creates the configured agent.

This separation makes it possible to change the model configuration without rewriting the agent’s behavioral instructions.

Switching Providers

Because the model is configured through the agent builder, changing providers can often be as simple as changing the model string. For example:

.model("openai:gpt-4.1-mini")

can be changed to:

.model("anthropic:claude-sonnet-4")

or:

.model("ollama:llama3")

The rest of the agent configuration can remain conceptually unchanged. However, provider portability does not guarantee identical behavior between models. Differences can include supported capabilities, response formats, tool behavior, context limits, latency, and provider-specific request requirements.

Provider and Tools

Providers work together with BindAI’s tool system. For example:

agent = (
    Agent.builder()
    .name("assistant")
    .model("openai:gpt-4.1-mini")
    .tools(search_tool, calculator_tool)
    .build()
)

The agent can then make use of registered tools when the model produces tool calls supported by the configured provider and model. Provider and model capabilities determine whether tool calling is supported. Applications should verify the selected provider/model capabilities before depending on tool calling.

Provider and Structured Output

BindAI agents can request structured output through run(). For example:

from pydantic import BaseModel


class User(BaseModel):
    name: str
    age: int


result = agent.run(
    "Generate a fictional user.",
    output=User,
)

print(result.output)

Structured-output conversion is performed by the agent execution layer. During the finish stage, BindAI attempts to parse the model response as JSON and construct the requested output type. If parsing or construction fails, the execution layer falls back to the raw response text. Provider capabilities still matter because the quality and reliability of structured output depend on the selected model and provider behavior. Applications should test the provider/model combinations they intend to support.

Provider and Streaming

The provider interface includes a stream() operation for streaming model output. At the agent level, applications can use:

for chunk in agent.stream_chat("Explain transformers."):
    print(chunk)

The low-level execution path obtains the stream from the configured provider. The provider capability model exposes a streaming flag indicating whether streaming is supported by the provider implementation. Streaming is useful for:

Chat interfaces
Interactive applications
Long responses
Real-time user experiences

Applications should verify streaming support before depending on it.

Provider and Memory

Memory is implemented at the BindAI agent/application layer rather than being tied to a particular model provider. For example:

agent = (
    Agent.builder()
    .name("assistant")
    .model("openai:gpt-4.1-mini")
    .memory(memory)
    .build()
)

The same general memory configuration can be used while changing the model provider. This separation allows model selection and application state management to evolve independently.

Provider and Knowledge

Knowledge and retrieval are also separate from the provider implementation. For example:

agent = (
    Agent.builder()
    .name("researcher")
    .model("openai:gpt-4.1-mini")
    .knowledge(knowledge)
    .retriever(retriever)
    .build()
)

The knowledge and retrieval components provide relevant context while the configured provider supplies the language model used for generation. This separation allows the same knowledge architecture to be used with different model providers.

Local Models

The provider abstraction allows applications to use local inference services. For example:

.model("ollama:llama3")

The rest of the agent can retain the same general structure:

agent = (
    Agent.builder()
    .name("assistant")
    .model("ollama:llama3")
    .instructions("You are a helpful assistant.")
    .build()
)

This makes it possible to experiment with local models without restructuring the application around a provider-specific SDK.

Custom Providers

BindAI’s provider architecture is designed around the ModelProvider abstraction and the core provider registry. A custom provider implementation needs to provide the common provider operations:

ModelProvider
    |
    +---- name
    |
    +---- generate()
    |
    +---- stream()
    |
    +---- capabilities

A provider implementation receives a ProviderConfiguration and can expose its supported capabilities through ProviderCapabilities. Providers can then be registered with the provider registry. Because provider APIs and registration mechanisms can evolve independently, custom provider implementations should follow the interfaces exposed by the BindAI version being used.

Provider Independence

Provider independence means that the application-level agent interface is separated from provider-specific model communication. For example:

agent = (
    Agent.builder()
    .name("assistant")
    .model("openai:gpt-4.1-mini")
    .instructions("You are a helpful assistant.")
    .build()
)

The model can later be changed:

.model("ollama:llama3")

without requiring the rest of the application to be rewritten around a provider-specific SDK. This is one of the primary benefits of the provider abstraction. Provider independence does not imply identical model behavior. Provider-specific capabilities and model behavior still need to be considered.

Provider Portability

The provider-qualified model format allows the same general agent architecture to be used with different providers. For example:

.model("openai:gpt-4.1-mini")

.model("anthropic:claude-sonnet-4")

.model("google:gemini-2.5-flash")

.model("groq:llama-3.3-70b-versatile")

.model("ollama:llama3")

.model("openrouter:openai/gpt-4.1-mini")

The agent’s tools, instructions, memory, knowledge, and workflow integration can remain conceptually separate from provider selection. However, provider portability does not mean that every model supports every capability. Always verify the capabilities of the selected provider/model combination before relying on features such as:

Tool calling
Structured output
Streaming
Vision
Embeddings
Reasoning
Particular context limits
Provider-specific features

Choosing a Provider

The appropriate provider depends on the application’s requirements. Consider:

Model capabilities
Hosting requirements
Privacy requirements
Latency
Cost
Tool-calling support
Structured-output support
Streaming support
Deployment environment
Local versus hosted inference

For local inference, Ollama provides a provider path for locally hosted models. For hosted applications, a managed provider or routing service may be appropriate. The important consideration is whether the selected provider/model combination satisfies the application’s actual requirements.

Provider Configuration in Development

A typical development environment can keep provider credentials in a .env file. For example:

OPENAI_API_KEY=your_api_key_here
ANTHROPIC_API_KEY=your_api_key_here
GEMINI_API_KEY=your_api_key_here
GROQ_API_KEY=your_api_key_here
OPENROUTER_API_KEY=your_api_key_here

Ollama can use:

OLLAMA_HOST=http://localhost:11434

Applications should load environment configuration through their normal configuration mechanism. Never commit the .env file when it contains real credentials. A project can also configure only the provider credentials it actually needs. For project-scoped provider credentials, BindAI can store connection credentials in the operating system credential store instead of placing them in .env or bindai.toml.

Provider Errors

Provider execution can fail for reasons such as:

Invalid credentials
Missing credentials
Unsupported model
Provider service errors
Network failures
Rate limits
Invalid requests
Provider account or quota restrictions

Applications should handle normal execution results and runtime exceptions appropriately. For a normal completed execution:

result = agent.run("Explain what BindAI is.")

if result.success:
    print(result.output)
else:
    print(result.error)

Provider failures that escape the execution pipeline are handled through the agent’s error callback and then re-raised. Provider-specific failures should not require the application to replace the overall agent abstraction.

Provider Testing

Provider integrations should be tested independently as well as through agent execution. Useful tests include:

Provider registration
Provider discovery
Provider creation
Authentication configuration
Model generation
Streaming
Tool calling when supported
Structured output when supported
Capability reporting
Error handling

Not every provider/model combination supports every capability identically, so integration tests should reflect the capabilities the application actually requires.

Complete Example

A complete agent can use the provider abstraction together with other BindAI capabilities:

from bindai import Agent


agent = (
    Agent.builder()
    .name("research-assistant")
    .model("openai:gpt-4.1-mini")
    .instructions(
        """
        You are a research assistant.
        Provide clear and concise answers.
        Use available tools and knowledge when appropriate.
        """
    )
    .tools(search)
    .memory(memory)
    .knowledge(knowledge)
    .retriever(retriever)
    .build()
)

result = agent.run("Research BindAI and summarize its architecture.")

if result.success:
    print(result.output)
else:
    print(result.error)

The provider can then be changed without fundamentally changing the rest of the agent configuration:

.model("anthropic:claude-sonnet-4")

or:

.model("ollama:llama3")

This demonstrates the separation between provider selection and application-level agent configuration.

Best Practices

Keep provider credentials out of source code.
Use environment variables, project-scoped connections, or an appropriate secret-management system for credentials.
Use the provider:model format when selecting a model.
Prefer Agent.builder() for agent configuration.
Keep provider-specific logic out of application-level business logic where practical.
Verify provider/model capabilities before relying on tool calling or structured output.
Test provider/model combinations used by the application.
Use local providers when local inference is appropriate.
Choose models based on the actual requirements of the task.
Keep provider configuration separate from agent instructions whenever possible.
Do not assume that different providers will produce identical behavior.
Check the provider capability metadata when an application depends on a specific feature.
Keep provider integrations modular so additional providers can be added without changing the core agent abstraction.

BindAI’s provider architecture gives applications a consistent agent interface while allowing the underlying model provider to change as requirements evolve.

​Providers

​Provider Architecture

​Supported Providers

​Configuring a Model

​Provider-Qualified Models

​Provider Configuration

​Environment Variables

​Project-Scoped Provider Connections

​Provider Interface

​Provider Capabilities

​Provider Registry

​Provider Bootstrap

​OpenAI

​Anthropic

​Google Gemini

​Groq

​Ollama

​OpenRouter

​Provider and Agent Configuration

​Switching Providers

​Provider and Tools

​Provider and Structured Output

​Provider and Streaming

​Provider and Memory

​Provider and Knowledge

​Local Models

​Custom Providers

​Provider Independence

​Provider Portability

​Choosing a Provider

​Provider Configuration in Development

​Provider Errors

​Provider Testing

​Complete Example

​Best Practices